home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / CrtTrace.3 < prev    next >
Text File  |  1994-09-20  |  8KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_CreateTrace(3)   Tcl Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_CreateTrace, Tcl_DeleteTrace - arrange for command  exe-
  12.      cution to be traced
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      Tcl_Trace
  18.      Tcl_CreateTrace(_i_n_t_e_r_p, _l_e_v_e_l, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  19.  
  20.      Tcl_DeleteTrace(_i_n_t_e_r_p, _t_r_a_c_e)
  21.  
  22. ARGUMENTS
  23.      Tcl_Interp         *_i_n_t_e_r_p          (in)      Interpreter
  24.                                                    containing
  25.                                                    command to  be
  26.                                                    traced      or
  27.                                                    untraced.
  28.  
  29.      int                _l_e_v_e_l            (in)      Only  commands
  30.                                                    at   or  below
  31.                                                    this   nesting
  32.                                                    level  will be
  33.                                                    traced.      1
  34.                                                    means     top-
  35.                                                    level commands
  36.                                                    only,  2 means
  37.                                                    top-level com-
  38.                                                    mands or those
  39.                                                    that       are
  40.                                                    invoked     as
  41.                                                    immediate
  42.                                                    consequences
  43.                                                    of   executing
  44.                                                    top-level com-
  45.                                                    mands    (pro-
  46.                                                    cedure bodies,
  47.                                                    bracketed com-
  48.                                                    mands,   etc.)
  49.                                                    and so on.
  50.  
  51.      Tcl_CmdTraceProc   *_p_r_o_c            (in)      Procedure   to
  52.                                                    call  for each
  53.                                                    command that's
  54.                                                    executed.  See
  55.                                                    below      for
  56.                                                    details on the
  57.                                                    calling
  58.                                                    sequence.
  59.  
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_CreateTrace(3)   Tcl Library Procedures
  71.  
  72.  
  73.  
  74.      ClientData         _c_l_i_e_n_t_D_a_t_a       (in)      Arbitrary
  75.                                                    one-word value
  76.                                                    to   pass   to
  77.                                                    _p_r_o_c.
  78.  
  79.      Tcl_Trace          _t_r_a_c_e            (in)      Token      for
  80.                                                    trace   to  be
  81.                                                    removed
  82.                                                    (return  value
  83.                                                    from  previous
  84.                                                    call        to
  85.                                                    Tcl_CreateTrace).
  86. _________________________________________________________________
  87.  
  88.  
  89. DESCRIPTION
  90.      Tcl_CreateTrace arranges for command tracing.  From now  on,
  91.      _p_r_o_c  will be invoked before Tcl calls command procedures to
  92.      process  commands  in  _i_n_t_e_r_p.   The   return   value   from
  93.      Tcl_CreateTrace  is  a  token  for  the  trace, which may be
  94.      passed to Tcl_DeleteTrace to remove the trace.  There may be
  95.      many  traces  in  effect simultaneously for the same command
  96.      interpreter.
  97.  
  98.      _P_r_o_c should have arguments and result that  match  the  type
  99.      Tcl_CmdTraceProc:
  100.  
  101.           typedef void Tcl_CmdTraceProc(
  102.                ClientData _c_l_i_e_n_t_D_a_t_a,
  103.                Tcl_Interp *_i_n_t_e_r_p,
  104.                int _l_e_v_e_l,
  105.                char *_c_o_m_m_a_n_d,
  106.                Tcl_CmdProc *_c_m_d_P_r_o_c,
  107.                ClientData _c_m_d_C_l_i_e_n_t_D_a_t_a,
  108.                int _a_r_g_c,
  109.                char *_a_r_g_v[]));
  110.  
  111.      The _c_l_i_e_n_t_D_a_t_a and  _i_n_t_e_r_p  parameters  are  copies  of  the
  112.      corresponding  arguments  given to Tcl_CreateTrace.  _C_l_i_e_n_t_-
  113.      _D_a_t_a typically points to an application-specific data struc-
  114.      ture  that describes what to do when _p_r_o_c is invoked.  _L_e_v_e_l
  115.      gives the nesting level of the command (1 for top-level com-
  116.      mands  passed  to  Tcl_Eval  by  the  application, 2 for the
  117.      next-level commands passed to Tcl_Eval as part of parsing or
  118.      interpreting  level-1  commands, and so on).  _C_o_m_m_a_n_d points
  119.      to a string containing the text of the command,  before  any
  120.      argument  substitution.  _C_m_d_P_r_o_c contains the address of the
  121.      command procedure that will be called to process the command
  122.      (i.e.   the   _p_r_o_c   argument   of  some  previous  call  to
  123.      Tcl_CreateCommand) and _c_m_d_C_l_i_e_n_t_D_a_t_a contains the associated
  124.      client  data  for  _c_m_d_P_r_o_c  (the  _c_l_i_e_n_t_D_a_t_a value passed to
  125.      Tcl_CreateCommand).  _A_r_g_c and _a_r_g_v give the  final  argument
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_CreateTrace(3)   Tcl Library Procedures
  137.  
  138.  
  139.  
  140.      information  that  will be passed to _c_m_d_P_r_o_c, after command,
  141.      variable, and backslash substitution.  _P_r_o_c must not  modify
  142.      the _c_o_m_m_a_n_d or _a_r_g_v strings.
  143.  
  144.      Tracing will only occur for commands at nesting  level  less
  145.      than or equal to the _l_e_v_e_l parameter (i.e. the _l_e_v_e_l parame-
  146.      ter to _p_r_o_c will always be less than or equal to  the  _l_e_v_e_l
  147.      parameter to Tcl_CreateTrace).
  148.  
  149.      Calls to _p_r_o_c will be made by  the  Tcl  parser  immediately
  150.      before  it  calls  the  command  procedure  for  the command
  151.      (_c_m_d_P_r_o_c).  This occurs after argument parsing and substitu-
  152.      tion,  so  tracing  for  substituted  commands occurs before
  153.      tracing of the commands containing  the  substitutions.   If
  154.      there is a syntax error in a command, or if there is no com-
  155.      mand procedure associated with a command name, then no trac-
  156.      ing  will  occur  for  that  command.  If a string passed to
  157.      Tcl_Eval contains multiple commands (bracketed, or  on  dif-
  158.      ferent  lines)  then  multiple calls to _p_r_o_c will occur, one
  159.      for each command.  The _c_o_m_m_a_n_d  string  for  each  of  these
  160.      trace  calls  will  reflect  only  a single command, not the
  161.      entire string passed to Tcl_Eval.
  162.  
  163.      Tcl_DeleteTrace removes a trace, so  that  no  future  calls
  164.      will  be  made  to  the procedure associated with the trace.
  165.      After Tcl_DeleteTrace returns, the caller should never again
  166.      use the _t_r_a_c_e token.
  167.  
  168.  
  169. KEYWORDS
  170.      command, create, delete, interpreter, trace
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.